home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / edit / me_cd.zip / MEMUTT.DOC < prev    next >
Lisp/Scheme  |  1988-10-11  |  30KB  |  635 lines
  1. ========================================================================
  2. ==        The ME Mutt Connection          Craig Durland  8/88 ==
  3. ========================================================================
  4.   This document describes the link between the Mutt programming langauge
  5. (see MUTT.DOC) and the Mutt Editor (see ME.DOC).
  6.  
  7. ========================================================================
  8. ==        The ME Mutt functions                      ==
  9. ========================================================================
  10. (append-to-register n [text])    [NUMBER [STRING] : VOID]
  11.   Append text or region to register n.
  12.   Register 0 is the kill buffer.  Registers 1,2,3,4 are general purpose.
  13.   For example:
  14.     If the region contains "This is a test" then
  15.       (clear-register 0)
  16.       (append-to-register 0) (append-to-register 0 " foo bar")
  17.     will set the kill buffer to "This is is a test foo bar".
  18.   Note: appending to a register that contains a rectangle does nothing.
  19.   See also:  clear-register, copy-rectangle, insert-register, the kill
  20.     buffer commmands in ME.DOC.
  21. (arg-flag)        [zip : BOOLEAN]
  22.   Check to see if somebody set the arg-prefix before calling this
  23.     routine (via (universal-argument) or (arg-prefix n)).
  24.   See also: arg-prefix.
  25. (arg-prefix [arg])    [[NUMBER] : NUMBER]
  26.   Get or set the universal-argument.
  27.   With an arg, its the same as ^U before a function.
  28.     Notes:
  29.       The arg-flag is set to TRUE.
  30.       This really sets two prefixes:  one for ME commands and one for
  31.     Mutt pgms.  ME commands and exe-key use and reset the prefix to
  32.     1.  Pgms can only read the prefix and so it will stay the same
  33.     for all children of a pgm unless it is changed by (arg-prefix
  34.     n).  If it is changed, all the children AND parents will see the
  35.     new value.  It is a good idea to make a copy of the value upon
  36.     entry to a pgm if it is possible that a child will do a
  37.     (arg-prefix n).
  38.       If prefix is not set, it is always 1 (and the arg-flag is FALSE)
  39.     when a pgm or ME command is run from the keyboard.
  40.   Note that there is a difference between (arg-prefix 1) and the default.
  41.     eg (arg-prefix 1)(delete-char) puts the deleted character into the kill
  42.     buffer but (delete-char) does not.
  43.   For example, to make META-n start the (universal-argument) count at n,
  44.     use the following (where n is 1,2,3,4,5,6,7,8 or 9):
  45.     (defun
  46.       META-arg { (arg-prefix (- (key-pressed) 0x230))(universal-argument) }
  47.       MAIN
  48.       {
  49.     (int j)
  50.     (for (j 1)(< j 10)(+= j 1)
  51.       (bind-to-key (concat "META-arg")(concat "M-" j)))
  52.       }
  53.     )
  54.   See also: (arg-flag), (universal-argument) in ME.DOC.
  55. (argc)        [zip : NUMBER]
  56.   The number of parameters on the command line when ME was invoked +1.
  57.   eg "ME foo bar" has argc == 3.
  58.   Use argv to look at the parameters.
  59. (argv)        [NUMBER : STRING]
  60.   The ME command line parameters.  There are argc of them, numbering
  61.     0...argc-1.  (argv 0) is the name of the program (ME) (unless you are
  62.     running on MS-DOS 2.x where it is ""), (argv 1) is the first file name
  63.     (which is loaded by ME), (argv 2) is the next file name, etc.
  64.   For example:
  65.     ; sequentially load the files specified on the command line
  66.     (int nth-file) ; file to load next (a global var initialized to 0)
  67.     (defun next-file
  68.     {
  69.       (if (== 0 nth-file)(nth-file 2))    ; already loaded first file
  70.       (if (< nth-file (argc))
  71.     { (visit-file (argv nth-file))(+= nth-file 1) }
  72.     (msg "All files read in.")
  73.       )
  74.     })
  75. (attached-buffer n | name)    [NUMBER|STRING : NUMBER]
  76.   If given a number, attached-buffer returns the buffer that is attached
  77.     to window n.  n==-1 means use the current window.
  78.   If given a name, attached-buffer returns the buffer that is named
  79.     name.  Returns -1 if there if the buffer does not exist.
  80.   For example:
  81.     if the third window is displaying buffer "foobar" and foobar is
  82.       the second buffer then:
  83.       (attached-buffer -1) and (attached-buffer 2) both return 1.
  84.       (attached-buffer "foobar") returns 1.
  85.       (attached-buffer "FOOBAR") returns -1.
  86.   See also: buffers, windows.
  87.  
  88. (buffer-created-hook)    [zip : zip]
  89.   This is called when a buffer is created and allows a pgm to set up
  90.     a buffer.
  91.   Note: You defun this pgm.
  92.   WARNING: This can give ME a headache.  Don't do anything fancy (like
  93.     switching buffers, inserting, etc).  Not even I know for sure what
  94.     is safe here.
  95.   BUGS: Does not get called on first file on command line.
  96.     eg me foo.bar - buffer-created-hook not called on foo.bar but
  97.     is called there after (assuming it is defuned in init.mut).
  98.     The elsleazo workaround is to put (buffer-created-hook) at the end
  99.       of init.mut (ie after the hook has been defuned).
  100.   See also:  buffer-var,  init.mut (an example of how to use 
  101.     buffer-created-hook to set modes based on file name extension).
  102. (buffer-flags n [x])        [NUMBER [NUMBER] : NUMBER]
  103.   Get or set the buffer flags.  There are 8 flags represented by the
  104.     lower 8 bits of x.
  105.     Bit   Flag
  106.     0x01  Modified.  1 if the buffer has been modified since last save.
  107.     0x02  NoCare.  Don't care about buffer contents.
  108.     0x04  Hidden.  Buffer is hidden from user.
  109.     The other bits are not used (currently) and may be used by pgms.
  110.   Notes:
  111.     The Modified flag reports the same info that buffer-modified does.
  112.       If you want to mark a buffer as not modified it is better to use
  113.       not-modified or buffer-modified because buffer-flags will not
  114.       update the modeline if the buffer is being displayed.
  115.     The NoCare flag is used whenever ME wants exit or change a buffer -
  116.       it is set, ME will not ask before changes are made.
  117.     A buffer with the Hidden flag set is invisible to the user -
  118.       (next-buffer) skips it, the help and command completion routines
  119.       ignore it.
  120.   ME only changes the Modified flag.
  121.   See also: buffer-modified, buffers.
  122. (buffer-modified n [bool])    [NUMBER [BOOLEAN] : BOOLEAN]
  123.   Check to see if buffer n is modified.
  124.   If n==-1 the current buffer is used.
  125.   (buffer-modified -1) : TRUE if the current buffer is modified.
  126.   (buffer-modified 0) : TRUE if the first buffer is modified.
  127.   (buffer-modified -1 FALSE) : mark the current buffer as not modified.
  128.   (buffer-modified n FALSE) : mark the nth buffer as not modified.
  129.   See also: buffer-flags, buffers, current-buffer, (not-modified).
  130. (buffer-name n)            [NUMBER : STRING]
  131.   Return the name of the nth buffer.
  132.   (buffer-name -1) returns the name of the current buffer.
  133.   (buffer-name 0) returns the name of the first buffer.
  134.   See also: buffers, current-buffer, file-name.
  135. (buffer-stats n array INT 6)    [NUMBER BLOB : VOID]
  136.   Get some stats on the nth buffer.  n==-1 means current buffer.
  137.   These  stats  are:  buffer-size  (in   characters),   dot  (number  of
  138.     characters  from the start of the  buffer),  lines  (number  of text
  139.     lines in the buffer),  buffer-row (the line in the buffer the dot is
  140.     on), wasted (the number of  characters  allocated  but not used) and
  141.     character-at-dot  (ASCII  value  - eg if  the  dot is on a "A"  then
  142.     character-at-dot==65).
  143.   Note that buffer-size may NOT be the same as the file size.
  144.   An example of a typical  buffer stats routine (ie whats bound to
  145.     "^X=") is:
  146.     (defun show-buffer-stats    ; bind this to "^X="
  147.     {
  148.       (INT buffer-size dot lines buffer-row wasted char-at-dot ratio)
  149.     
  150.       (buffer-stats -1 (pointer buffer-size))
  151.       (ratio 0)(if (!= 0 buffer-size)(ratio (/ (* 100 dot) buffer-size)))
  152.       (msg "Row=" buffer-row " (of " lines ")"
  153.       " Col=" (current-column) " Y=" (window-row)
  154.       " CH=0x" (tobase char-at-dot 16) " .=" dot
  155.       " (" ratio "% of " buffer-size "))
  156.     })
  157. (buffer-var n [value])        [NUMBER [NUMBER] : NUMBER]
  158.   Each buffer has 10 numeric variables (numbered 0,1,...9) associated
  159.     with it.  These vars are not used by ME - they are there for pgm use.
  160.     They live and die with the buffer and are not initialized.
  161.   eg (buffer-var 0 123) sets var 0 to 123.  (msg (buffer-var 0)) displays
  162.     123 in the minibuffer.  (x (buffer-var 0)) assigns 123 to x.
  163.     (buffer-var 1 (+ (buffer-